/***************************************************************************
 * Copyright (C) 2005 Global Biodiversity Information Facility Secretariat.
 * All Rights Reserved.
 *
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 ***************************************************************************/
package org.gbif.wdpa.service;

import java.util.List;
import java.util.Map;

import org.gbif.wdpa.model.*;

/**
 * This interface defines the methods that the GBIF-WDPA project uses to get the data from
 * the Backend. This Interface represent the single Service layer that its exposed as AMF
 * using Granite. In the future other web services might be also linked to this interface.
 * 
 * The actual client widget that has been developed in Flex only uses two methods:
 * 
 * -getAreaData
 * -getAreaMapData
 * 
 * But the others are exposed here in case they are needed.
 * 
 * @author jatorre
 */
public interface WDPAManager {
	/**
	 * Get a list of data providers, DataProvider, who has data for a certain Protected Area. 
	 * @param areaId Area Id from wich area the providers are requested.
	 * @return a list of DataProvider
	 * 
	 * @author jatorre
	 */
	public List<DataProvider> getAreaDataProviders(int areaId);
	
	/**
	 * get the taxa list and stats for an area.
	 * @return a Map with the following keys:
	 * 
	 * taxonStats 		= list of TaxonStats objects for area
	 * numObservation	= total number of observations on the area
	 * numOtherBor		= total number of other Basis Of Record that are not observations
	 * 					  and specimens
	 * numSpecimens		= total number of specimens
	 * total			= the sum of the previous ones.
	 * 
	 * @author jatorre
	 */	
	public Map<String,Object> getAreaTaxaStats(int areaId);

	/**
	 * Recive a list of Ids and return all the stat data for each area
	 * and geometry as a set of polygons.
	 * 
	 * @param areaId Id of the requested area.
	 * @return a Map with the following keys:
	 * 
	 * @author jatorre
	 */
	@SuppressWarnings("unchecked")
	public List getAreasByIds(Integer[] areaIds);

	/**
	 * Get a list of Id, and name of areas that insersect the provided
	 * coordinates.
	 * 
	 * @param lat latitude of the point
	 * @param lng longitude of the point
	 * @return list of areas with id and name that intersect the point.
	 * 
	 * @author jatorre
	 */ 
	@SuppressWarnings("unchecked")
	public List getAreasByCoordinates(float lat,float lng);	
	
	/**
	 * Get the list of areas in a certain country provided
	 * by an iso_code.
	 * 
	 * @param isoCountry 2 letter ISO code of the country.
	 * @return the name of the protected area as a String.
	 * 
	 * @author jatorre
	 */ 	
	public Map<String,Object> getAreasBasicListByCountry(String isoCountry);		
	
	/**
	 * Get taxonomy for a certain tile
	 * 
	 * @param tileX 
	 * @param tileY 
	 * @param zoom
	 * @param areaId 
	 * @return the name of the protected area as a String.
	 * 
	 * @author jatorre
	 */ 	
	@SuppressWarnings("unchecked")
	public Map<String,Object> getTileTaxonomy(int tileX,int tileY, int zoom, int areaId);

	/**
	 * Get cells for a certain tile and area. This is highly influenced by the
	 * database structure.
	 * 
	 * @see org.gbif.wdpa.dao.jdbc.WDPAManagerImpl#getAreaCellsByTileArea(String)
	 * 
	 * @param tileX 2 tile X coordinate
	 * @param tileY 2 tile Y coordinate
	 * @param tile zoom level
	 * @param areaId Area Id
	 * @return
	 * 
	 * @author jatorre
	 */	
	@SuppressWarnings("unchecked")
	public Map<String,Object> getAreaCellsByTileArea(Integer tileX,Integer tileY, Integer zoom, Integer areaId);
	
}
